Commands and functions for JavaScript variables
Aim
In this topic you find the commands and functions that you can use to extract process tracking data with JavaScript code.
Get started
We assume that you have basic knowledge about JavaScript. To get started with JavaScript we recommend this online compiler:
https://repl.it/languages/javascript
Many courses on the internet concern JavaScript for web page developers. An excellent course more focused on JavaScript as a data processing tool can be found here:
https://www.youtube.com/watch?v=Bv_5Zv5c-Ts
Extract subject features
Use the functions below to extract the position and other features of your subjects.
▪GetSubjectCenter, GetSubjectNose, GetSubjectTail
▪GetSubjectArea, GetSubjectChangedArea
Extract other data
Query data
Use the functions below to ask simple questions, like Is the subject in the central zone? The software gives a boolean answer (true/false).
▪IsInZone (discontinued)
▪IsSubjectCenterInZone, IsSubjectNoseInZone, IsSubjectTailInZone
Calculate
Returns the x,y coordinates of the center-point, nose-point or tail-base point of the subjects in a single-subject trial, respectively. Use this function in a single-subject experiment, or in a multi-subject experiment to extract the body points of the focal subject.
▪syntax
GetCenter()
GetNose()
GetTail()
▪example 1
In the following example, the code verifies if the center point of the subject, when found, is in the zone named Zone 1.
const g_Zone = "Zone 1";
(...)
function Process()
{
var ptC = GetCenter();
if (ptC)
{
g_bInZone = IsInZone(g_Zone, ptC);
}
▪example 2
In the following example, we calculate the average x coordinate of the center point and the nose point.
var ptC = GetCenter();
var ptN = GetNose();
var x_avg = ptC.x + ptN.x;
GetSubjectCenter, GetSubjectNose, GetSubjectTail
Returns the x, y coordinates of a body point of a specific subject in a multi-subject experiment. You can use this function to compare the position of different subjects in the same JavaScript variable.
See also the sample experiment Subject Counter with JavaScript code XT160, which you can find on my.noldus.com, under Downloads > EthoVision XT > Drivers and tools.
▪syntax
GetSubjectCenter(Subject name)
GetSubjectNose(Subject name)
GetSubjectTail(Subject name)
▪arguments
Subject name: the name of one of the subjects as defined in the Experiment Settings.
▪example
In the following loop (not shown entirely), the center point of each subject is loaded in the variable pt.
const g_aSubjects = ["Subject 1", "Subject 2", "Subject 3", ... ]
(...)
for (i = 0; i < g_aSubjects.length; ++i)
{
var pt = GetSubjectCenter(g_aSubjects[i]);
(...)
Note that g_aSubject.length function gets the length of the array variable g_aSubjects which contains the names of the subjects. The variable g_aSubjects is defined at the top of the script.
Returns the current value of the subject’s area (in practice, the yellow blob that you see during tracking), and the area that has changed from the previous sample, respectively. Use these functions for
▪The subject in a single-subject experiment.
▪The focal subject in a multi-subject experiment. Here “focal” refers to the subject for which the statistics are calculated.
Areas are expressed in internal units (mm2), independent of the units selected in the Experiment Settings. For information on the Changed area, see Rotation.
▪syntax
GetArea()
GetChangedArea()
▪example
var a = GetArea();
var ca = GetChangedArea();
▪notes
GetArea and GetChangedArea are not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.
GetSubjectArea, GetSubjectChangedArea
GetSubjectArea returns the current value of the area of a specified subject in a multi-subject experiment.
GetSubjectChangedArea returns the area of the subject in a multi-subject experiment that has changed from the previous sample. For information on the Changed area, see Rotation.
The subject’s area is the area of the yellow blob that you see during tracking. It is expressed in internal units (mm2), independent of the units selected in the Experiment Settings.
▪syntax
GetSubjectArea(“subject name”)
GetChangedArea(“subject name”)
where Subject name is the name of the subject specified in the Experiment settings.
▪example 1
var a = GetSubjectArea(“Subject 1”);
▪example 2
// This for loop extracts the area for a number of subjects
for (i = 0; i < g_aSubjects.length; ++i)
{
var AreaSubj = GetSubjectArea(g_aSubjects[i]);
...
}
▪notes
GetSubjectArea and GetSubjectChangedArea are not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.
GetElongation returns the current value of Body elongation for
▪The subject in a single-subject experiment.
▪The focal subject in a multi-subject experiment. Here “focal” refers to the subject for which the statistics are calculated.
It is expressed as a number between 0 and 1. To obtain the same as the dependent variable Body elongation, multiply it by 100.
▪syntax
GetElongation()
▪example
var y = GetElongation();
if (y != null)
{
SetOutput(y*100);
}
else
{
SetOutputMissing();
}
▪notes
GetElongation is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.
Returns the current value of Body elongation for a specified subject in a multi-subject experiment. It is expressed as a number between 0 and 1. To obtain the same as the dependent variable Body elongation, multiply it by 100.
▪syntax
GetSubjectElongation(“Subject name”)
where Subject name is the name of the subject specified in the Experiment settings.
▪example
// This for loop extracts the body elongation for a number of subjects
for (i = 0; i < g_aSubjects.length; ++i)
{
var EloSubj = GetSubjectElongation(g_aSubjects[i]);
...
}
▪notes
GetSubjectElongation is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ body contour.
Returns the current value of the Head direction variable for
▪The subject in a single-subject experiment.
▪The focal subject in a multi-subject experiment. Here “focal” refers to the subject for which the statistics are calculated.
It is expressed in radians. Note that the Head direction dependent variable provided by EthoVision XT is expressed in degrees. To convert your JavaScript variable to degrees, see the example below.
▪syntax
GetViewDirection()
▪example
var dir = GetViewDirection();
If you want to extract the head direction in degrees, convert the value of head direction to degrees with the following formula:
function toDegrees(angle)
{
return angle * (180 / Math.PI);
}
(...)
var dir = GetViewDirection();
angle = toDegrees(dir);
▪notes
GetViewDirection is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ head direction.
Returns the value of the Head direction of a specified subject in a multi-subject experiment, for the current sample. The value is given in radians. Note that the Head direction dependent variable provided by EthoVision XT is expressed in degrees. To convert your JavaScript variable to degrees, see the example in GetViewDirection.
▪syntax
GetSubjectViewDirection(“subject name”)
where Subject name is the name of the subject specified in the Experiment settings.
▪example
// This for loop extracts the Head direction in radians for a number of subjects
for (i = 0; i < g_aSubjects.length; ++i)
{
var HDirSubj = GetSubjectViewDirection(g_aSubjects[i]);
...
}
▪notes
GetSubjectViewDirection is not available when using Deep learning with two subjects per arena, because this method does not record the subjects’ head direction.
Returns the sample time (in seconds) of the sample currently processed. You can use this function to calculate the latency of an event that you cannot obtain through the other dependent variables.
note The sample time in this function is the track time, that is, the time elapsed from the start of the track (the first sample), not the start of the trial.
▪syntax
GetSampleTime()
▪example
The following example outputs the value of the current sample time. If it is not found, a missing value is assigned with the SetOutputMissing command (see below).
function Process()
{
var st = GetSampleTime();
if (st!= null)
{
SetOutput(st);
}
else
{
SetOutputMissing();
}
Returns the current proportion of pixels in the arena that have changed intensity above the specified Activity threshold from the previous video frame. This proportion can be between 0 (no pixel in the arena has changed intensity value above the threshold) and 1 (all pixels in the arena have changed intensity value above the threshold). A pixel change value of 0.156 (expressed as proportion) corresponds to an Body angle value without smoothing of 15.6%.
To use this variable, you must select Activity analysis in the Experiment Settings and define the threshold value in Activity settings in the Detection settings. For information on the pixel change, see Body angle.
▪syntax
GetPixelChange()
▪example
var a = GetPixelChange();
Returns the distance of a (body) point from a zone. The distance is zero if the body point is within the zone. Distances are expressed in internal units (mm), independent of the units selected in the Experiment Settings.
▪syntax
GetDistanceToZone(Zone, Point)
▪arguments
Zone: the name of the zone as it appears in the Arena Settings; e.g. “Platform”.
Point: the name of the point; usually a body point.
▪example
const g_strZone = "Object";
(...)
function Process()
{
var ptNose = GetNose();
var dist = GetDistanceToZone(g_strZone, ptNose);
This is similar to GetDistanceToZone; it returns the distance from the specified point of interest. Distances are expressed in internal units (mm), independent of the units selected in the Experiment Settings.
▪syntax
GetDistanceToPoi(Point of interest, Point)
▪arguments
Point of interest: the name of the point of interest as it is defined in the Arena Settings.
Point: the name of the point to which distance is determined; usually a body point.
This command returns the value of an event scored manually using the Manual Scoring function. If you work with Live Mouse Tracker, this command also works with the events listed under Raw Live Mouse Tracker data in the Analysis profile.
▪syntax
GetBehaviorEvent(behavior)
GetBehaviorEvent(behavior, receiver)
▪arguments
Behavior: The name of the behavior as in the Manual Scoring Settings or listed under Raw Live Mouse Tracker data in the Analysis profile.
Receiver (optional): The name of the receiver, in case of multi-subject tracking.
▪return values
undefined: no behavior event
1: start of a state event
2: stop
4: point event
▪example
The following code gets the values of the behavior Sleep that was scored. The function UpdateState at the top copies the values of Sleep, 1 or 2 to a new state variable g_bState with values true or false, respectively.
var g_bState = false;
function UpdateState(evt)
{
if (evt != undefined)
{
if (evt == 1)
{
g_bState = true;
}
else if (evt == 2)
{
g_bState = false;
}
}
}
function Process()
{
var evt = GetBehaviorEvent("Sleep");
UpdateState(evt);
SetOutput(g_bState);
}
Returns the event that represent a command to a hardware device.
▪syntax
GetCommand(Device name, Command name)
▪arguments
Device name: the name of the device specified in EthoVision XT. For example, “Device A”. To know the device name, in the Arena Settings click the Arena-Hardware Mapping button, under Device name click the cell of the device you require and press Ctrl+C. Paste the text into the JavaScript code as Device name.
Command name: the name of the command used in the Trial Control Settings. For example, “Drop pellet”. To know the command name, open the Trial Control Settings, locate the Action box that contains that command and click Settings. Take note of the text near Action to perform. Enter this text in the JS code as Command name.
▪example
In the following example, JavaScript reads the command “Drop pellet” of a Pellet dispenser with name Device A and outputs the value for each sample of the track (1 = drop a pellet; missing value = no pellets dropped).
function Process()
{
var DropPellet = GetCommand("Device A", "Drop pellet");
SetOutput(DropPellet);
}
Returns the value of a hardware signal.
▪syntax
GetSignal(Device name, Signal name)
▪arguments
Device name: the name of the device specified in EthoVision XT. For example, “Device B”. To know the device name, in the Arena Settings click the Arena-Hardware Mapping button, under Device name click the cell of the device you require and press Ctrl+C. Paste the text into the JavaScript code as Device name.
Signal name: the name of the signal that you want to acquire. For example, “Number of licks”. To know the signal name, open an Analysis profile, click the button next to Hardware continuous, select a Device type, Device, and Signal. Take note of the text near Signal, and enter this text in the JS code as Signal name.
▪example
In the following example, JavaScript reads the value of the signal “Number of licks” of a lickometer (Device B) and outputs it for each sample of the track.
function Process()
{
var s = GetSignal("Device B", "Number of licks");
SetOutput(s);
}
With the new Point statement you can define a point in space.
▪syntax
new Point(x,y,z)
▪arguments
x, y, z (z is optional): The coordinates in mm based on the calibration axes and origin in the Arena Settings.
▪example
pt1 = new Point(200, 300);
▪note
You cannot visualize the position of points defined with JavaScript. To do so, define points in the Arena Settings.
With this command you can extract the coordinates of a point of interest of the center of a zone or arena. Note that GetPointPoi returns the position of the point, then you have to extract the coordinates with additional commands (e.g. x = pt.x).
▪syntax
GetPointPoi(point)
▪arguments
point: The name of the point or the zone or arena, of which you want to find the center.
▪example
const g_zone = "Zone 1";
function Start()
{
}
function Stop()
{
}
function Process()
var pt = GetPointPoi(g_zone);
var xc = pt.x;
var xy = pt.y;
This function has been replaced by other functions in EthoVision XT 19 (see below).
▪For single-subject tracking: see IsPointInZone
▪For multi-subject tracking: see IsSubjectCenterInZone, IsSubjectNoseInZone, IsSubjectTailInZone.
You can still use IsInZone in your code, but it won’t work properly when analyzing data points in hidden zones.
IsSubjectCenterInZone, IsSubjectNoseInZone, IsSubjectTailInZone
Use this function to determine if a body point of a subject is within a zone. The zone must be defined in the Arena Settings. The return value is boolean (true or false).
▪syntax
IsSubjectCenterInZone(Subject name, Zone name);
IsSubjectNoseInZone(Subject name, Zone name);
IsSubjectTailInZone(Subject name, Zone name);
▪arguments
Subject name: the name of one of the subjects listed in the Experiment Settings.
Zone name: the name of the zone of interest defined in the Arena Settings; for example, "Zone 1". You can specify the name directly (“Zone 1” with quotes), or a variable that contains that name. The zone can be a single zone, a cumulative zone, an entry zone, or a hidden zone.
▪example - one subject
var bC = IsSubjectCenterInZone(“Subject 1”, “Zone 1”);
var bN = IsSubjectNoseInZone(“Subject 1”, “Zone 1”);
var bT = IsSubjectTailInZone(“Subject 1”, “Zone 1”);
or
const g_sZone = "Zone 1"
var bC = IsSubjectCenterInZone(“Subject 1”, g_sZone);
var bN = IsSubjectNoseInZone(“Subject 1”, g_sZone);
var bT = IsSubjectTailInZone(“Subject 1”, g_sZone);
▪example - multiple subjects
var bC1 = IsSubjectCenterInZone(“Subject 1”, “Zone 1”);
var bC2 = IsSubjectCenterInZone(“Subject 2”, “Zone 1”);
Use this function to determine if a point (a body point, or a point of interest) is within a zone. The zone must be defined in the Arena Settings. The return value is boolean (true or false).
▪syntax
IsPointInZone(Zone name, Point name)
▪arguments
Zone name: the name of a zone defined in the Arena Settings; for example, "Zone 1".
Point name: The name of a body point or a point of interest defined in the Arena Settings.
▪example
pt = GetCenter();
var b1 = IsPointInZone(“Zone 1”, pt);
or
pt = new Point (10, 10);
var b1 = IsPointInZone (“Zone 1”, pt);
Checks if two points are equal.
▪syntax
point1.Equals(point2).
▪arguments
point 1: the first point
point 2: the second point
▪example
The variable b gets the value 1 if the two points pt1 (the center of the subject) and pt2 (a point in space defined with the new statement) have the same coordinates.
var pt1 = GetCenter();
var pt2 = new Point(1.0, 2.0);
var b = pt1.Equals(pt2);
▪errors
If one of the two points is null, the value is not calculated and an invalid reference is returned.
Determines if the subject specified (argument) is currently the actor (focal subject) of the track being analyzed. The return value is boolean (true or false). You can use this function to skip comparisons and calculations that do not make sense.
▪syntax
IsSubjectActor(Subject name)
Where Subject name is the name of one of the subjects listed in the Experiment Settings.
▪example
In this example a for loop scans the list of i subjects Subject 1, Subject 2, etc. contained in the array g_aSubjects[i] and calculates the distance between the focal subject (that is, the subject of the currently analyzed track) and the subject i.
for (i = 0; i < g_aSubjects.length; ++i)
var ptSubj = GetSubjectCenter(g_aSubjects[i]);
(...)
//invoke Distance function
var Dist = Distance(ptFocal, ptSubj);
Obviously at some point in this loop the focal subject and the subject i are the same individual. You can exclude the distance calculation focal-to-focal by inserting an extra check.
var b = IsSubjectActor(g_aSubject[i]);
if b = true
{
//invoke distance function
To calculate the distance between two points, see Point.Distance. You can also use the code here below and invoke the function in your script. Distance is expressed in internal units (mm), independent of the units selected in the Experiment Settings.
▪function
// Function to calculate distance between two points
function Distance(pt1, pt2)
{
var dx = pt1.x - pt2.x;
var dy = pt1.y - pt2.y;
return Math.sqrt(dx * dx + dy * dy);
}
▪example of function call
//Get the center point of subject 1 and subject 2
var cSubj1 = GetSubjectCenter(“Subject 1”);
var cSubj2 = GetSubjectCenter(“Subject 2”);
//call distance function
var Dist = Distance(cSubj1, cSubj2);
▪errors
If one of the two points is null, the value is not calculated.
Calculates the distance between two points. Distance is expressed in internal units (mm), independent of the units selected in the Experiment Settings.
▪syntax
point1.Distance(point2)
▪arguments
point1: the first point
point2: the second point
▪example
var pt1 = GetCenter();
var pt2 = GetNose();
var dist = pt1.Distance(pt2);
▪errors
If one of the two points is null, the value is not calculated and an invalid reference is returned.
Returns the angle in radians between three points. The name suggests that this function is restricted to turn angles but you can use it to calculate any angle formed by three points in general. See also Turn angle
▪syntax
TurnAngle(Point 1, Point 2, Point 3)
▪arguments
Point 1: the name of the begin point.
Point 2: the name of the middle point.
Point 3: the name of the end point. This is the point at the current sample time, while Point 1 and Point 2 are the points at two immediately preceding sample times.
▪example
ta = TurnAngle(g_aPoints[0], g_aPoints[1], g_aPoints[2]);
where g_aPoints is an array variable of length 3.
Remember that TurnAngle is in radians. At the top of the code, define a function to obtain the value in degrees:
function toDegrees(angle)
{
return angle * (180 / Math.PI);
}
(...)
var tadg = toDegrees(ta);
▪errors
If any of the three points is null, the value is not calculated.
Returns the value of heading in radians based on two sample points. See Heading
▪syntax
Heading(Point 1, Point 2)
▪arguments
Point 1: Begin point.
Point 2: End point.
To calculate heading, Point 1 is the point at the previous sample time and Point 2 the point at the current sample time.
▪example
var hd = Heading(g_aPoints[0], g_aPoints[1]);
where g_aPoints is an array variable of length 2.
At the top of the code, define a function to obtain the value in degrees:
function toDegrees(angle)
{
return angle * (180 / Math.PI);
}
(...)
var hdg = toDegrees(hd);
▪errors
If one of the two points is null, the value is not calculated.
Assigns a value to the JavaScript variable for the current sample time.
▪syntax
SetOutput(Value)
SetOutput(Output, Value)
▪arguments
Value: the value that you want to assign to the variable at the current sample time.
▪For JavaScript Continuous variables: a rational number.
▪For JavaScript State variables: true or false.
▪For JavaScript Event variables: 0 or 1.
Output: Output number. When the variable has just one value per sample, like in most applications, then you do not need to specify Output. When the variable has multiple outputs, like in a state variable with 4 possible states, specify the output in each line (beginning from zero). For example
SetOutput(0, bOutput1); //write first state
SetOutput(1, bOutput2); //write second state
SetOutput(2, bOutput3); //write third state
SetOutput(3, bOutput4); //write fourth state
▪example
if (x != null)
{
SetOutput(x);
}
▪errors
If the value is null or undefined, the output will be missing.
▪notes
When the variable has multiple outputs, remember to specify the Number of outputs at the bottom of the JavaScript window.
Assigns a missing value to the JavaScript variable for the current sample time.
▪syntax
SetOutputMissing()
▪example
In the following example, if the value of x is not null, it is assigned to the output of the JavaScript variable; otherwise it is set to missing.
if (x != null)
{
SetOutput(x);
}
else
{
SetOutputMissing();
}
See also